<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
	<head>
		<title>Secret features of Inform</title>
<link rel="stylesheet" href="https://www.w3schools.com/w3css/4/w3.css">
<link rel="stylesheet" href="https://www.w3schools.com/lib/w3-theme-black.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.3.0/css/font-awesome.min.css">

<link href="docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
		<meta name="viewport" content="width=device-width initial-scale=1">
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
		<meta http-equiv="Content-Language" content="en-gb">

<link href="docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="docs-assets/ConsoleText-Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
		
	</head>
	<body class="commentary-font">
		<nav role="navigation">
		<h1><a href="index.html"><img src="docs-assets/Inform.png" height=72> </a></h1>
<ul><li><a href="index.html"><span class="selectedlink">home</span></a></li>
</ul><h2>Compiler</h2><ul>
<li><a href="structure.html">structure</a></li>
<li><a href="inbuildn.html">inbuild</a></li>
<li><a href="inform7n.html">inform7</a></li>
<li><a href="intern.html">inter</a></li>
<li><a href="services.html">services</a></li>
<li><span class="unlink">secrets</span></li>
</ul><h2>Other Tools</h2><ul>
<li><a href="inblorbn.html">inblorb</a></li>
<li><a href="inform6.html">inform6</a></li>
<li><a href="inpolicyn.html">inpolicy</a></li>
</ul><h2>Resources</h2><ul>
<li><a href="extensions.html">extensions</a></li>
<li><a href="kits.html">kits</a></li>
</ul><h2>Repository</h2><ul>
<li><a href="https://github.com/ganelson/inform"><img src="docs-assets/github.png" height=0> github</a></li>
</ul><h2>Related Projects</h2><ul>
<li><a href="https://github.com/ganelson/inweb"><img src="docs-assets/github.png" height=0> inweb</a></li>
<li><a href="https://github.com/ganelson/intest"><img src="docs-assets/github.png" height=0> intest</a></li>
</ul>
		</nav>
		<main role="main">
		<!-- Weave of 'Secret features of Inform' generated by inweb -->
<div class="breadcrumbs">
    <ul class="crumbs"><li><a href=".html"></a></li><li><b>Secret features of Inform</b></li></ul></div>
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>&#167;1. </b>Undocumented features of Inform are no longer very secret (here you are reading
about them, after all), but they can be hard to find by raking through the source
code at random. What we mean by "undocumented features" here are capabilities
intentionally included in Inform, but not mentioned in any of the user-facing
documentation. That documentation used to be just the two books built in to the
apps (Writing with Inform and The Recipe Book), but those are now supplemented
by the manuals for the three command-line tools <a href="inform7/index.html" class="internal">inform7</a>, <a href="inbuild/index.html" class="internal">inbuild</a> and
<a href="inter/index.html" class="internal">inter</a>, which cover many features invisible from within the app and at
present available only for command-line users.
</p>

<p class="commentary">This page covers a handful of other features still, but which are intended mainly
for maintainers of Inform and may change at any time without notice.
</p>

<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>&#167;2. </b>In working out what the compiler is doing (or has just done), the debugging log
is always the first thing to investigate. This a text file like a running
journal of what the compiler is doing; if it halts partway, either with problem
messages or an internal error, then the log is still written up to that point, and
can be revealing. The log can be viewed in the Inform apps, but usually
only if an "advanced" preference setting has been ticked. Once that is done,
the log appears as one of the tabs in the Results pane after each compilation
(successful or not). A similar preference setting enables the Inform 6 output
to be viewed, too, though of course only if the compiler gets that far.
</p>

<p class="commentary">The compiler is more instrumented than a first look at the log might suggest.
Most of its "debugging aspects" are switched off by default: if they were all
switched on, the log would be simply enormous. Each aspect has a textual name &mdash;
for example, "predicate calculus" shows the logical propositions formed and
simplified inside the compiler. (On each run, the bottom of the debugging log
lists the range of available aspects.) There are four ways to change what
aspects are switched on:
</p>

<ul class="items"><li>(1) Add a sentence like "Include predicate calculus in the debugging log." to
the source text for the project. For obvious reasons, this can only take effect
after sentences begin to be understood by the compiler, but in practice that's
early enough to be useful.
</li><li>(2) Add a command-line switch like <span class="extract"><span class="extract-syntax">-log predicate-calculus</span></span> (note that any
spaces in the name are replaced by hyphens) when running <span class="extract"><span class="extract-syntax">inform7</span></span> from the
command line. <span class="extract"><span class="extract-syntax">-log list</span></span> prints a list of the aspects.
</li><li>(3) If you're interested in how Inform is reading an assertion sentence (say, "A
ball is on the oak table"), try placing the special sentences <span class="extract"><span class="extract-syntax">*.</span></span> and <span class="extract"><span class="extract-syntax">*.</span></span>
either side of it. This switches on, and then off again, a convenient mode of
logging which shows (i) the primary verb, (ii) the full sentence diagram, (iii)
any logical propositions derived from that, and (iv) any inferences drawn as a
result. The log output is mostly self-explanatory, but the notation <span class="extract"><span class="extract-syntax">X =14 Y</span></span> (or
some other number) means that the assertion-maker is coupling the tree nodes <span class="extract"><span class="extract-syntax">X</span></span>
and <span class="extract"><span class="extract-syntax">Y</span></span> together in Case 14 of the <a href="assertions-module/4-ass.html" class="internal">Assertions (in assertions)</a> algorithm. For
example, in the log output from the following, you'll
see <span class="extract"><span class="extract-syntax">[ball/PROPER_NOUN_NT] =36 [is on/RELATIONSHIP_NT]</span></span>:
</li></ul>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">The</span><span class="plain-syntax"> </span><span class="identifier-syntax">French</span><span class="plain-syntax"> </span><span class="identifier-syntax">Kitchen</span><span class="plain-syntax"> </span><span class="identifier-syntax">is</span><span class="plain-syntax"> </span><span class="identifier-syntax">a</span><span class="plain-syntax"> </span><span class="identifier-syntax">room</span><span class="plain-syntax">. </span><span class="identifier-syntax">An</span><span class="plain-syntax"> </span><span class="identifier-syntax">oak</span><span class="plain-syntax"> </span><span class="identifier-syntax">table</span><span class="plain-syntax"> </span><span class="identifier-syntax">is</span><span class="plain-syntax"> </span><span class="identifier-syntax">in</span><span class="plain-syntax"> </span><span class="identifier-syntax">the</span><span class="plain-syntax"> </span><span class="identifier-syntax">Kitchen</span><span class="plain-syntax">.</span>
<span class="plain-syntax">*. </span><span class="identifier-syntax">A</span><span class="plain-syntax"> </span><span class="identifier-syntax">ball</span><span class="plain-syntax"> </span><span class="identifier-syntax">is</span><span class="plain-syntax"> </span><span class="identifier-syntax">on</span><span class="plain-syntax"> </span><span class="identifier-syntax">the</span><span class="plain-syntax"> </span><span class="identifier-syntax">oak</span><span class="plain-syntax"> </span><span class="identifier-syntax">table</span><span class="plain-syntax">. *.</span>
</pre>
<ul class="items"><li>(4) If you're interested in how Inform is reading a phrase inside a rule or
phrase definition, and particularly in the running of the Dash typechecker, try
placing the special phrases <span class="extract"><span class="extract-syntax">***;</span></span> and <span class="extract"><span class="extract-syntax">***;</span></span> either side of whatever phrase
you're interested in. This shows exactly what code path through Dash is being
followed, and which kind conformances are being checked. For example:
</li></ul>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">To</span><span class="plain-syntax"> </span><span class="identifier-syntax">consider</span><span class="plain-syntax"> (</span><span class="identifier-syntax">N</span><span class="plain-syntax"> - </span><span class="identifier-syntax">a</span><span class="plain-syntax"> </span><span class="identifier-syntax">number</span><span class="plain-syntax">):</span>
<span class="plain-syntax">    ***;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">showme</span><span class="plain-syntax"> </span><span class="identifier-syntax">N</span><span class="plain-syntax"> </span><span class="identifier-syntax">times</span><span class="plain-syntax"> </span><span class="identifier-syntax">N</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    ***.</span>
</pre>
<ul class="items"><li>(5) It is also possible to write <span class="extract"><span class="extract-syntax">*** "predicate calculus";</span></span> to switch on just
a single named debugging aspect, so:
</li></ul>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">Every</span><span class="plain-syntax"> </span><span class="identifier-syntax">turn</span><span class="plain-syntax">:</span>
<span class="plain-syntax">    *** </span><span class="string-syntax">"predicate calculus"</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">now</span><span class="plain-syntax"> </span><span class="identifier-syntax">the</span><span class="plain-syntax"> </span><span class="identifier-syntax">rock</span><span class="plain-syntax"> </span><span class="identifier-syntax">is</span><span class="plain-syntax"> </span><span class="identifier-syntax">in</span><span class="plain-syntax"> </span><span class="identifier-syntax">the</span><span class="plain-syntax"> </span><span class="identifier-syntax">bucket</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    ***.</span>
</pre>
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>&#167;3. </b>Inform compiles first to an intermediate representation called Inter, and only
then compiles that in turn to its actual output. The Inter produced is then
discarded and normally never leaves memory, so it's invisible to the user. When
debugging, though, we sometimes want to see what it was.
</p>

<p class="commentary">Two special debugging aspects are provided for this.
</p>

<ul class="items"><li>&#9679; "Include Inter in the debugging log." will cause Inform (strictly speaking,
<a href="inter/index.html" class="internal">inter</a>) to write out the entire compiled Inter tree, in its textual form, into
the debugging log. Be warned that this is an awful lot of output, and will cause
a pause of an extra couple of seconds just to write.
</li><li>&#9679; "Include Inform Inter in the debugging log." will cause only the Inter
generated by Inform itself to be logged. Logged earlier in the run, this is a
smaller tree not yet containing material from kits such as BasicInformKit or
WorldModelKit. (Smaller, yes: small, no.)
</li><li>&#9679; If you're interested only in the code for a single phrase or rule, place the
pseudo-phrase <span class="extract"><span class="extract-syntax">*** "inter";</span></span> somewhere (anywhere &mdash; makes no difference) inside
its body. Note that this shows the Inter generated by the whole definition, and of
course that never happens if problem messages are generated instead. For example:
Every turn:
	*** "inter";
	now the rock is in the bucket.
</li></ul>
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>&#167;4. </b>The "Test... with... " feature of Inform is familiar to most users, since it's
used by almost all of the examples, usually with source text like:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">Test</span><span class="plain-syntax"> </span><span class="identifier-syntax">me</span><span class="plain-syntax"> </span><span class="identifier-syntax">with</span><span class="plain-syntax"> </span><span class="string-syntax">"examine box / take box"</span><span class="plain-syntax">.</span>
</pre>
<p class="commentary">Less well-known is that it can also run unit tests built in to the compiler. For example:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">Test</span><span class="plain-syntax"> </span><span class="identifier-syntax">description</span><span class="plain-syntax"> (</span><span class="identifier-syntax">internal</span><span class="plain-syntax">) </span><span class="identifier-syntax">with</span><span class="plain-syntax"> </span><span class="identifier-syntax">a</span><span class="plain-syntax"> </span><span class="identifier-syntax">number</span><span class="plain-syntax"> </span><span class="identifier-syntax">which</span><span class="plain-syntax"> </span><span class="identifier-syntax">is</span><span class="plain-syntax"> </span><span class="identifier-syntax">even</span><span class="plain-syntax">.</span>
</pre>
<p class="commentary">The test here is called <span class="extract"><span class="extract-syntax">description</span></span>. The marker <span class="extract"><span class="extract-syntax">(internal)</span></span> is what causes
this sentence to be read as an internal test case. Most tests, <span class="extract"><span class="extract-syntax">description</span></span>
among them, then expect some details to follow the word <span class="extract"><span class="extract-syntax">with</span></span>. In this case,
it's a description, "a number which is even", and what the test does is to
convert this to a logical proposition and print that proposition out.
</p>

<p class="commentary">What happens is not that <a href="inform7/index.html" class="internal">inform7</a> prints the test output to the console, or
even to the debugging log. It compiles the test output into the story file it is
generating, so that this is printed out when the story file runs. That may sound
needlessly indirect, but it's convenient both in the app and also for intest to
check. Add the above test sentence to some project, click Go in the app and you
see the result.
</p>

<ul class="items"><li>&#9679; <span class="extract"><span class="extract-syntax">Test description (internal)</span></span> converts a description such as "a number which
is even" to a proposition, showing the kinds of its variables and whether they
are free or bound:
</li></ul>
<pre class="displayed-code all-displayed-code code-font">
<span class="constant-syntax">1</span><span class="plain-syntax">. </span><span class="identifier-syntax">a</span><span class="plain-syntax"> </span><span class="identifier-syntax">number</span><span class="plain-syntax"> </span><span class="identifier-syntax">which</span><span class="plain-syntax"> </span><span class="identifier-syntax">is</span><span class="plain-syntax"> </span><span class="identifier-syntax">even</span>
<span class="plain-syntax">&lt;&lt; </span><span class="identifier-syntax">number</span><span class="plain-syntax">(</span><span class="identifier-syntax">x</span><span class="plain-syntax">) &amp; </span><span class="identifier-syntax">even</span><span class="plain-syntax">(</span><span class="identifier-syntax">x</span><span class="plain-syntax">) &gt;&gt;</span>
<span class="identifier-syntax">x</span><span class="plain-syntax"> (</span><span class="identifier-syntax">free</span><span class="plain-syntax">) - </span><span class="identifier-syntax">number</span><span class="plain-syntax">.</span>
</pre>
<ul class="items"><li>&#9679; <span class="extract"><span class="extract-syntax">Test eps (internal)</span></span> tests just the EPS-file-maker part of the spatial map
index, and therefore isn't very useful.
</li><li>&#9679; <span class="extract"><span class="extract-syntax">Test evaluation (internal)</span></span> is used for verifying that literal arithmetic
quantities written in unusual notations are evaluated correctly. For example,
<span class="extract"><span class="extract-syntax">Test evaluation (internal) with 1 sq m divided by 20cm.</span></span>
</li><li>&#9679; <span class="extract"><span class="extract-syntax">Test headline (internal)</span></span> is not a test at all! It simply prints out a
dividing subheading in the test output &mdash; if a project makes hundreds of
internal tests then these subheadings make the output much more legible. For
example, <span class="extract"><span class="extract-syntax">Test headline (internal) with Unquantified relative clauses.</span></span> puts the
subheading "Unquantified relative clauses" at this point in the test output.
</li><li>&#9679; <span class="extract"><span class="extract-syntax">Test index (internal)</span></span> produces just one element of the index for test
purposes, as a chunk of HTML. For example, <span class="extract"><span class="extract-syntax">Test index (internal) with Mp.</span></span>
tests the <span class="extract"><span class="extract-syntax">Mp</span></span> (spatial map) element.
</li><li>&#9679; <span class="extract"><span class="extract-syntax">Test kind (internal)</span></span> is not much use, but can produce four different
listings of the kinds known to Inform, according to whether the <span class="extract"><span class="extract-syntax">with ...</span></span> text
is <span class="extract"><span class="extract-syntax">1</span></span>, <span class="extract"><span class="extract-syntax">2</span></span>, <span class="extract"><span class="extract-syntax">3</span></span> or <span class="extract"><span class="extract-syntax">4</span></span>.
</li><li>&#9679; <span class="extract"><span class="extract-syntax">Test pattern (internal)</span></span> is for testing that the rather complex grammar
used for "action patterns" in Inform is being parsed correctly. It has two
different forms: if the <span class="extract"><span class="extract-syntax">with ...</span></span> text begins with <span class="extract"><span class="extract-syntax">list</span></span> then a list of
actions is expected, and if not, then the text should describe a single action
(though possibly quite vaguely). For example:
</li></ul>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">Test</span><span class="plain-syntax"> </span><span class="identifier-syntax">pattern</span><span class="plain-syntax"> (</span><span class="identifier-syntax">internal</span><span class="plain-syntax">) </span><span class="identifier-syntax">with</span><span class="plain-syntax"> </span><span class="identifier-syntax">asking</span><span class="plain-syntax"> </span><span class="identifier-syntax">Hans</span><span class="plain-syntax"> </span><span class="identifier-syntax">to</span><span class="plain-syntax"> </span><span class="identifier-syntax">try</span><span class="plain-syntax"> </span><span class="identifier-syntax">taking</span><span class="plain-syntax"> </span><span class="identifier-syntax">the</span><span class="plain-syntax"> </span><span class="identifier-syntax">counter</span><span class="plain-syntax">.</span>
<span class="identifier-syntax">Test</span><span class="plain-syntax"> </span><span class="identifier-syntax">pattern</span><span class="plain-syntax"> (</span><span class="identifier-syntax">internal</span><span class="plain-syntax">) </span><span class="identifier-syntax">with</span><span class="plain-syntax"> </span><span class="identifier-syntax">list</span><span class="plain-syntax"> </span><span class="identifier-syntax">looking</span><span class="plain-syntax"> </span><span class="identifier-syntax">or</span><span class="plain-syntax"> </span><span class="identifier-syntax">taking</span><span class="plain-syntax"> </span><span class="identifier-syntax">inventory</span><span class="plain-syntax"> </span><span class="identifier-syntax">in</span><span class="plain-syntax"> </span><span class="identifier-syntax">the</span><span class="plain-syntax"> </span><span class="identifier-syntax">presence</span><span class="plain-syntax"> </span><span class="identifier-syntax">of</span><span class="plain-syntax"> </span><span class="identifier-syntax">Hans</span><span class="plain-syntax"> </span><span class="identifier-syntax">in</span><span class="plain-syntax"> </span><span class="identifier-syntax">the</span><span class="plain-syntax"> </span><span class="identifier-syntax">Laboratory</span><span class="plain-syntax">.</span>
</pre>
<ul class="items"><li>&#9679; <span class="extract"><span class="extract-syntax">Test refinery (internal)</span></span> shows how assertion sentences are "refined". For
example, <span class="extract"><span class="extract-syntax">Test refinery (internal) with Jane is a woman.</span></span>
</li><li>&#9679; <span class="extract"><span class="extract-syntax">Test sentence (internal)</span></span> is very like <span class="extract"><span class="extract-syntax">description</span></span>, but expects a whole
sentence, that is, something with no free variables rather than one:
</li></ul>
<pre class="displayed-code all-displayed-code code-font">
<span class="constant-syntax">1</span><span class="plain-syntax">. </span><span class="identifier-syntax">everyone</span><span class="plain-syntax"> </span><span class="identifier-syntax">likes</span><span class="plain-syntax"> </span><span class="identifier-syntax">Peter</span>
<span class="plain-syntax">&lt;&lt; </span><span class="identifier-syntax">ForAll</span><span class="plain-syntax"> </span><span class="identifier-syntax">x</span><span class="plain-syntax"> </span><span class="identifier-syntax">IN</span><span class="plain-syntax">&lt; </span><span class="identifier-syntax">person</span><span class="plain-syntax">(</span><span class="identifier-syntax">x</span><span class="plain-syntax">) </span><span class="identifier-syntax">IN</span><span class="plain-syntax">&gt; : </span><span class="identifier-syntax">amity</span><span class="plain-syntax">(</span><span class="identifier-syntax">x</span><span class="plain-syntax">, '</span><span class="identifier-syntax">peter</span><span class="plain-syntax">') &gt;&gt;</span>
<span class="identifier-syntax">x</span><span class="plain-syntax"> - </span><span class="identifier-syntax">object</span><span class="plain-syntax">.</span>
</pre>
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>&#167;5. </b>inform7 has a test suite of roughly 2000 test cases, some of which are large
and elaborate. Running through this test suite must be done at the command line
(indeed, the tests are not shipped inside the apps, only as part of the inform
Git repository). The <a href="intest/index.html" class="internal">intest</a> tool is provided for this, and reading the
<a href="intest/index.html" class="internal">intest</a> manual is a good place to begin. A test suite to be operated by
<a href="intest/index.html" class="internal">intest</a> is configured by a <span class="extract"><span class="extract-syntax">*.intest</span></span> file, and the full details of how the
I7 suite works are laid out in <span class="extract"><span class="extract-syntax">inform/inform7/Tests/inform7.intest</span></span>. About 25%
of the tests are the Examples from the manuals; another 25% more or less
systematically poke at language features, and edge cases which proved tricky in
the past; and the remaining 50% test that the compiler produces correct problem
messages.
</p>

<p class="commentary">Tests in the suite can be divided up into the following categories:
</p>

<ul class="items"><li>&#9679; Those in <span class="extract"><span class="extract-syntax">inform/inform7/Tests/Test Basic</span></span> are Basic Inform tests, run
through the compiler in <span class="extract"><span class="extract-syntax">-basic</span></span> mode, meaning that the language features for
interactive fiction, the command parser and the world model are all missing.
(These tests run relatively quickly as a result.) With no command parser loop,
such programs run by printing some output and stopping.
</li><li>&#9679; Those in <span class="extract"><span class="extract-syntax">inform/inform7/Tests/Test Cases</span></span> are standard tests of Inform not
related to Examples in the documentation. This is a mixed bag which has
accumulated over the years.
</li><li>&#9679; Those in <span class="extract"><span class="extract-syntax">inform/resources/Documentation/Examples</span></span> are the examples from the
manuals &mdash; this makes up about 25% of the whole suite, and in practice tests
interactive-fiction features of Inform pretty systematically, besides ensuring
that the examples in the manual do what we claim that they do. Note that the
name of an example shown in the manual may not be the same as its Intest case
name: thus, "Bruneseau's Journey" has test case name <span class="extract"><span class="extract-syntax">Candle</span></span>. But you can use
intest's <span class="extract"><span class="extract-syntax">-find</span></span> feature if stuck:
</li></ul>
<pre class="ConsoleText-displayed-code all-displayed-code code-font">
<span class="ConsoleText-element-syntax">$</span><span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-function-syntax">../intest/Tangled/intest</span><span class="ConsoleText-plain-syntax"> inform7</span><span class="ConsoleText-identifier-syntax"> -find</span><span class="ConsoleText-plain-syntax"> Bruneseau</span>
<span class="ConsoleText-plain-syntax">Test cases matching 'Bruneseau':</span>
<span class="ConsoleText-plain-syntax">Candle = Bruneseau's Journey</span>
</pre>
<ul class="items"><li>&#9679; A few test cases are extracted and run from the extension documentation for
extensions supplied with Inform, such as "Locksmith".
</li><li>&#9679; Those in <span class="extract"><span class="ConsoleText-extract-syntax">inform/inform7/Tests/Test Internals</span></span> run internal test cases (see
above).
</li><li>&#9679; Those in <span class="extract"><span class="ConsoleText-extract-syntax">inform/inform7/Tests/Test Makes</span></span> are a small number of
demonstration programs which are hybrids running partly in C, partly in Inform.
These are built using individual makefiles &mdash; hence the name. The test cases
correspond to the example projects in the documentation on this: see
<a href="inform7/M-cifc.html" class="internal">Calling Inform from C (in inform7)</a>.
</li><li>&#9679; Those in <span class="extract"><span class="ConsoleText-extract-syntax">inform/inform7/Tests/Test Problems</span></span> are Inform source texts
expected to cause the compiler to halt with a problem message: they check that
it does in fact do so, and that the problem is correctly worded. See below.
</li><li>&#9679; Those in <span class="extract"><span class="ConsoleText-extract-syntax">inform/inform7/Tests/Test Releases</span></span> are for testing the release
instructions which <a href="inform7/index.html" class="internal">inform7</a> generates and supplies to <a href="inblorb/index.html" class="internal">inblorb</a>. (Note that
<a href="inblorb/index.html" class="internal">inblorb</a> itself is not run in these tests: only the instructions are checked.
But <a href="inblorb/index.html" class="internal">inblorb</a> has its own test suite, in which of course it is run.)
</li></ul>
<p class="commentary firstcommentary"><a id="SP6" class="paragraph-anchor"></a><b>&#167;6. </b>Each individual test has a name. The following naming conventions apply:
</p>

<ul class="items"><li>&#9679; No two different cases have the same name.
</li><li>&#9679; If a test case name ends in <span class="extract"><span class="ConsoleText-extract-syntax">-G</span></span>, it will be compiled to Glulx and run
through the <span class="extract"><span class="ConsoleText-extract-syntax">dumb-glulxe</span></span> interpreter.
</li><li>&#9679; If it ends <span class="extract"><span class="ConsoleText-extract-syntax">-C</span></span>, it will be compiled to ANSI C, then run through a C
compiler to produce a stand-alone executable, and that is what will then be run.
</li><li>&#9679; If the name has neither of these endings, it will be compiled to the
Z-machine and run through the <span class="extract"><span class="ConsoleText-extract-syntax">dumb-frotz</span></span> interpreter.
</li><li>&#9679; Names beginning <span class="extract"><span class="ConsoleText-extract-syntax">BIP-</span></span> are Basic Inform tests which systematically verify
that language features work. These tests mostly come in all three flavours, so
for example <span class="extract"><span class="ConsoleText-extract-syntax">BIP-Let</span></span>, <span class="extract"><span class="ConsoleText-extract-syntax">BIP-Let-G</span></span> and <span class="extract"><span class="ConsoleText-extract-syntax">BIP-Let-C</span></span> check the same functionality
when code-generating for the Z-machine, for Glulx and for C. (In a few cases to
do with real arithmetic, there's no Z-machine test.)
</li><li>&#9679; Names beginning <span class="extract"><span class="ConsoleText-extract-syntax">PM_</span></span> are tests of problem messages: for example,
<span class="extract"><span class="ConsoleText-extract-syntax">PM_ConflictedReturnKinds</span></span> or <span class="extract"><span class="ConsoleText-extract-syntax">PM_PropertiesEquated</span></span>. Almost every I7 problem
message has a code-name like this, and a corresponding test case. Though these
code-names are not displayed on the Results page shown in the Inform app when a
misbehaving project generates these problems, the code-names of any issued
problem messages are listed in the debugging log, which also gives a file and
line number reference to the Inform source code showing where the problem was
generated.
</li></ul>
<p class="commentary firstcommentary"><a id="SP7" class="paragraph-anchor"></a><b>&#167;7. </b>The complete test suite takes a long time to run &mdash; typically 10 to 11 minutes
on the author's computer in 2022, even running 16 simultaneous tests on
different cores. It's sometimes more practical to run subsets of the suite. For
example, if debugging the part of Inform which generates C code from Inter,
there's no point verifying the problem messages or the 900 or so tests which
compile to Z or Glulx.
</p>

<ul class="items"><li>&#9679; The Intest keywords <span class="extract"><span class="ConsoleText-extract-syntax">cases</span></span>, <span class="extract"><span class="ConsoleText-extract-syntax">examples</span></span>, and <span class="extract"><span class="ConsoleText-extract-syntax">problems</span></span> catch just the Test
Cases, document examples, and Test Problems cases respectively.
</li><li>&#9679; There are also "test groups" stored in <span class="extract"><span class="ConsoleText-extract-syntax">inform/inform7/Tests/Groups</span></span>. See
the <a href="intest/index.html" class="internal">intest</a> documentation for how to set up these groups, though they're
pretty self-explanatory.
</li></ul>
<p class="commentary">For example, these three commands:
</p>

<pre class="ConsoleText-displayed-code all-displayed-code code-font">
<span class="ConsoleText-element-syntax">$</span><span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-function-syntax">../intest/Tangled/intest</span><span class="ConsoleText-plain-syntax"> inform7 all</span>
<span class="ConsoleText-element-syntax">$</span><span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-function-syntax">../intest/Tangled/intest</span><span class="ConsoleText-plain-syntax"> inform7 problems</span>
<span class="ConsoleText-element-syntax">$</span><span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-function-syntax">../intest/Tangled/intest</span><span class="ConsoleText-plain-syntax"> inform7 :calculus</span>
</pre>
<p class="commentary">run the full test suite, just the Test Problems cases, and just the <span class="extract"><span class="ConsoleText-extract-syntax">:calculus</span></span>
group respectively. (Note the colon.) Particularly useful groups include <span class="extract"><span class="ConsoleText-extract-syntax">:c</span></span>,
which performs every test involving C output, and <span class="extract"><span class="ConsoleText-extract-syntax">:basic</span></span>, which performs the
whole BIP sub-suite.
</p>

<p class="commentary firstcommentary"><a id="SP8" class="paragraph-anchor"></a><b>&#167;8. </b>Internal errors in <a href="inform7/index.html" class="internal">inform7</a> generate the infamous "abject failure" problem
message. These are essentially failed assertions in the compiler, but they cause
a clean termination of the process with exit code 1, just as any more orthodox
problem message would. A Results page in HTML is generated normally. As a
result, they're no harder for the GUI apps to deal with than any other sort of
problem would be.
</p>

<p class="commentary">Harder to handle is an actual crash of the <a href="inform7/index.html" class="internal">inform7</a> executable, in which an
abrupt exit occurs where no problem message is generated: say if it dereferences
a null pointer, or divides by zero. This of course should never happen, but we
want the GUI apps to be able to cope if it does. And in order to test that, we
give <a href="inform7/index.html" class="internal">inform7</a> the ability to simulate such crashes.
</p>

<p class="commentary">This is done with three words too unspeakable to write, the "secret hieroglyphs
of dread power". They're actually not much to look at. The first is:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">ni</span><span class="plain-syntax">--</span><span class="identifier-syntax">crash</span><span class="plain-syntax">--1 </span><span class="identifier-syntax">is</span><span class="plain-syntax"> </span><span class="identifier-syntax">a</span><span class="plain-syntax"> </span><span class="identifier-syntax">room</span><span class="plain-syntax">.</span>
</pre>
<p class="commentary">This crashes out with exit code 1. The second and third are much the same, but
are written <span class="extract"><span class="extract-syntax">ni--crash--10</span></span> and <span class="extract"><span class="extract-syntax">ni--crash--11</span></span>, giving exit codes 10 and 11.
(On MacOS, at least, these are what result from derefencing a bad pointer or
overflowing the stack through infinite recursion.)
</p>

<p class="commentary firstcommentary"><a id="SP9" class="paragraph-anchor"></a><b>&#167;9. </b>If Inform does crash, or throw an internal error, or even simply produce an
unwanted problem message, but in circumstances which are unclear, then it's
useful to see a stack backtrace at the point where the error came to light.
This is where Intest's <span class="extract"><span class="extract-syntax">-debug</span></span> feature is useful. For example:
</p>

<pre class="ConsoleText-displayed-code all-displayed-code code-font">
<span class="ConsoleText-element-syntax">$</span><span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-function-syntax">../intest/Tangled/intest</span><span class="ConsoleText-plain-syntax"> inform7</span><span class="ConsoleText-identifier-syntax"> -debug</span><span class="ConsoleText-plain-syntax"> Acidity</span>
</pre>
<p class="commentary">This runs the test <span class="extract"><span class="ConsoleText-extract-syntax">Acidity</span></span>, but with the <span class="extract"><span class="ConsoleText-extract-syntax">inform7</span></span> executable running in
the lldb debugger (on MacOS, anyway), and moreover with it set to deliberately
cause a division by zero after any problem message is generated. This forces
<span class="extract"><span class="ConsoleText-extract-syntax">inform7</span></span> to exit into the debugger, at which point a stack backtrace can be
seen (in lldb, anyway) by typing <span class="extract"><span class="ConsoleText-extract-syntax">bt</span></span>.
</p>

<p class="commentary">Of course, Inform is unlikely to crash on any of the tests in the regular test
suite: more likely you have some wacky source text causing a crash or unwanted
problem message, but which isn't in the suite. In that case, though, you just
need to create a temporary test case for it &mdash; the author likes to keep this as the
file <span class="extract"><span class="ConsoleText-extract-syntax">inform/inform7/Tests/Test Cases/temp.txt</span></span>, and then:
</p>

<pre class="ConsoleText-displayed-code all-displayed-code code-font">
<span class="ConsoleText-element-syntax">$</span><span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-function-syntax">../intest/Tangled/intest</span><span class="ConsoleText-plain-syntax"> inform7</span><span class="ConsoleText-identifier-syntax"> -debug</span><span class="ConsoleText-plain-syntax"> temp</span>
</pre>
<p class="commentary">does the trick. But be sure not to add this temporary file to the repository.
</p>

<!-- End of weave -->

		</main>
	</body>
</html>

